---
title: "Getting started"
sidebarTitle: "Getting started"
---

### Docker-compose dev images
You can use `docker-compose.dev.yaml` to start Keep in a development mode.

First, clone the Keep repo:
```
git clone https://github.com/keephq/keep.git && cd keep
```

Next, run
```
docker compose -f docker-compose.dev.yml up
```

### Install Keep CLI

First, clone Keep repository:

```shell
git clone https://github.com/keephq/keep.git && cd keep
```

Install Keep CLI

```shell
poetry install
```

To access the Keep CLI activate the environment, and access from shell.

```shell
poetry shell
```

From now on, Keep should be installed locally and accessible from your CLI, test it by executing:

```
keep version
```

## Enable Auto Completion

**Keep's CLI supports shell auto-completion, which can make your life a whole lot easier 😌**

If you're using zsh

```shell title=~/.zshrc
eval "$(_KEEP_COMPLETE=zsh_source keep)"
```

If you're using bash

```bash title=~/.bashrc
eval "$(_KEEP_COMPLETE=bash_source keep)"
```

> Using eval means that the command is invoked and evaluated every time a shell is started, which can delay shell responsiveness. To speed it up, write the generated script to a file, then source that.


### Testing

Run unittests:
```bash
poetry run coverage run --branch -m pytest --ignore=tests/e2e_tests/
```

Run E2E tests (run Keep locally before):
```bash
poetry run playwright install;
poetry run coverage run --branch -m pytest -s tests/e2e_tests/
```

### Migrations

Migrations are automatically executed on a server startup. To create a migration:
```bash
alembic -c keep/alembic.ini revision --autogenerate -m "Your message"
```

Hint: make sure your models are imported at `./api/models/db/migrations/env.py` for autogenerator to pick them up.

## VS Code (or Cursor)
Run Keep from your VS Code (or Cursor) after cloning the repo by adding this configurations to your `.vscode/launch.json`:

```json
{
    "version": "0.2.0",
    "configurations": [
      {
        "name": "Keep Backend",
        "type": "debugpy",
        "request": "launch",
        "program": "keep/cli/cli.py",
        "console": "integratedTerminal",
        "justMyCode": false,
        "python": "venv/bin/python",
        "args": ["--json", "api","--multi-tenant"],
        "env": {
            "PYDEVD_DISABLE_FILE_VALIDATION": "1",
            "PYTHONPATH": "${workspaceFolder}/",
            "PUSHER_APP_ID": "1",
            "SECRET_MANAGER_DIRECTORY": "./state/",
            "PUSHER_HOST": "localhost",
            "PUSHER_PORT": "6001",
            "PUSHER_APP_KEY": "keepappkey",
            "PUSHER_APP_SECRET": "keepappsecret",
            "LOG_FORMAT": "dev_terminal",
        }
      },
      {
        "name": "Keep Simulate Alerts",
        "type": "debugpy",
        "request": "launch",
        "program": "scripts/simulate_alerts.py",
        "console": "integratedTerminal",
        "justMyCode": false,
        "python": "venv/bin/python",
        "env": {
          "PYDEVD_DISABLE_FILE_VALIDATION": "1",
          "PYTHONPATH": "${workspaceFolder}/",
          "KEEP_API_URL": "http://localhost:8080",
          "KEEP_API_KEY": "some-api-key"
        }
      },
      {
        "name": "Keep Frontend",
        "type": "node-terminal",
        "request": "launch",
        "command": "npm run dev",
        "cwd": "${workspaceFolder}/keep-ui",
      }
    ]
}
```

Install dependencies:
```
python3.11 -m venv venv;
source venv/bin/activate;
pip install poetry;
poetry install;
cd keep-ui && npm i && cd ..;
```

Set frontend envs:
```
cp keep-ui/.env.local.example keep-ui/.env.local;
echo "\n\n\n\nNEXTAUTH_SECRET="$(openssl rand -hex 32) >> keep-ui/.env.local;
```

Launch Pusher ([soketi](https://soketi.app/)) container in parallel:
```bash
docker run -d -p 6001:6001 -p 9601:9601 -e SOKETI_USER_AUTHENTICATION_TIMEOUT=3000 -e SOKETI_DEFAULT_APP_KEY=keepappkey -e SOKETI_DEFAULT_APP_SECRET=keepappsecret -e SOKETI_DEFAULT_APP_ID=1 quay.io/soketi/soketi:1.4-16-debian
```


## VS Code (or Cursor) + Docker
<Info>For this guide to work, the [VS Code Docker](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker) extension is required.</Info>
<Tip>In air-gapped environments, you might consider building the container on an internet-connected computer, exporting the image using docker save, transferring it with docker load in the air-gapped environment, and then using the run configuration.</Tip>

In cases where you want to develop Keep but are unable to run it directly on your local laptop (e.g., with Windows), or if you lack access to all of its dependencies (e.g., in air-gapped environments), you can still accomplish this using VS Code (or Cursor) and Docker.

To achieve this, follow these steps:

1. Clone Keep and open it with VS Code (or Cursor)
2. Create a tasks.json file to build and run the Keep API and Keep UI containers.
3. Create a launch.json configuration to start the containers and attach a debugger to them.
4. Profit.


### Clone Keep and open it with VS Code (or Cursor)
```
git clone https://github.com/keephq/keep.git && cd keep
code .
```

### Create tasks.json

#### including building the containers
```
{
    "version": "2.0.0",
    "tasks": [
        // The API and UI containers needs to be in the same docker network
        {
            "label": "docker-create-network",
            "type": "shell",
            "command": "docker network create keep-network || true",
            "problemMatcher": []
        },
        // Build the api container
        {
            "label": "docker-build-api-dev",
            "type": "docker-build",
            "dockerBuild": {
                "context": "${workspaceFolder}",
                "dockerfile": "${workspaceFolder}/Docker/Dockerfile.dev.api",
                "tag": "keep-api-dev:latest"
            }
        },
        // Run the api container
        {
            "label": "docker-run-api-dev",
            "type": "docker-run",
            "dependsOn": [
                "docker-build-api-dev", "docker-create-network"
            ],
            "python": {
                "args": [
                    "api"
                ],
                "file": "./keep/cli/cli.py"
            },
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-api-dev:latest",
                "containerName": "keep-api",
                "ports": [
                    {
                        "containerPort": 8080,
                        "hostPort": 8080
                    }
                ],
                "env": {
                    "DEBUG": "1",
                    "SECRET_MANAGER_TYPE": "FILE",
                    "USE_NGROK": "false",
                    "AUTH_TYPE": "DB"
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}"
                    }
                ]
            }
        },
        // Build the UI container
        {
            "label": "docker-build-ui",
            "type": "docker-build",
            "dockerBuild": {
                "context": "${workspaceFolder}",
                "dockerfile": "${workspaceFolder}/Docker/Dockerfile.dev.ui",
                "tag": "keep-ui-dev:latest"
            }
        },
        // Run the UI container
        {
            "type": "docker-run",
            "label": "docker-run-ui",
            "dependsOn": [
                "docker-build-ui", "docker-create-network"
            ],
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-ui-dev:latest",
                "containerName": "keep-ui",
                "env": {
                    // Uncomment for fully debug
                    // "DEBUG": "*",
                    "NODE_ENV": "development",
                    "API_URL": "http://keep-api:8080",
                    "AUTH_TYPE": "DB",
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}/keep-ui"
                    }
                ],
                "ports": [
                    {
                        "containerPort": 9229,
                        "hostPort": 9229
                    },
                    {
                        "containerPort": 3000,
                        "hostPort": 3000
                    }
                ],
                "command": "npm run dev",
            },
            "node": {
                "package": "${workspaceFolder}/keep-ui/package.json",
                "enableDebugging": true
            }
        }
    ]
}

```

#### without building the containers
<Tip>To start Keep without building the containers, you'll need to have `keep-api-dev` and `keep-ui-dev` images loaded into your docker.</Tip>

```
{
    "version": "2.0.0",
    "tasks": [
        # The API and the UI needs to be in the same docker network
        {
            "label": "docker-create-network",
            "type": "shell",
            "command": "docker network create keep-network || true",
            "problemMatcher": []
        },
        # Run the API container
        {
            "label": "docker-run-api-dev",
            "type": "docker-run",
            "dependsOn": [
                "docker-create-network"
            ],
            "python": {
                "args": [
                    "api"
                ],
                "file": "./keep/cli/cli.py"
            },
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-api-dev:latest",
                "containerName": "keep-api",
                "ports": [
                    {
                        "containerPort": 8080,
                        "hostPort": 8080
                    }
                ],
                "env": {
                    "DEBUG": "1",
                    "SECRET_MANAGER_TYPE": "FILE",
                    "USE_NGROK": "false",
                    "AUTH_TYPE": "DB"
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}"
                    }
                ]
            }
        },
        # Run the UI container
        {
            "type": "docker-run",
            "label": "docker-run-ui",
            "dependsOn": [
                "docker-create-network"
            ],
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-ui-dev:latest",
                "containerName": "keep-ui",
                "env": {
                    // Uncomment for fully debug
                    // "DEBUG": "*",
                    "NODE_ENV": "development",
                    "API_URL": "http://keep-api:8080",
                    "AUTH_TYPE": "DB"
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}/keep-ui"
                    }
                ],
                "ports": [
                    {
                        "containerPort": 9229,
                        "hostPort": 9229
                    },
                    {
                        "containerPort": 3000,
                        "hostPort": 3000
                    }
                ],
                "command": "npm run dev",
            },
            "node": {
                "package": "${workspaceFolder}/keep-ui/package.json",
                "enableDebugging": true
            }
        }
    ]
}
```

### Create launch.json

```
{
        "name": "Docker: Keep API",
        "type": "docker",
        "request": "launch",
        "preLaunchTask": "docker-run-api-dev",
        "removeContainerAfterDebug": true,
        "containerName": "keep-api",
        "python": {
          "pathMappings": [
            {
              "localRoot": "${workspaceFolder}",
              "remoteRoot": "/app"
            }
          ],
          "module": "keep.cli.cli"
        }
      },
      {
        "name": "Docker: Keep UI",
        "type": "docker",
        "request": "launch",
        "removeContainerAfterDebug": true,
        "preLaunchTask": "docker-run-ui",
        "containerName": "keep-api",
        "platform": "node",
        "node": {
          "package": "${workspaceFolder}/keep-ui/package.json",
          "localRoot": "${workspaceFolder}/keep-ui"
        }
      },
```
